@turf/helpers
Advanced tools
The @turf/helpers package is part of the Turf.js library, which is a modular geospatial engine written in JavaScript. It provides functions to create various simple geometrical features such as points, lines, and polygons, and to manipulate these geometries in various ways. This package is particularly useful for developers working with geographic information systems (GIS) and spatial analysis in web applications.
Creating Points
This function creates a GeoJSON Point feature using the provided coordinates. It is useful for representing locations on a map.
const point = turf.point([5, 10]);Creating LineStrings
This function creates a GeoJSON LineString feature from an array of positions. It is useful for mapping routes or paths.
const line = turf.lineString([[5, 10], [20, 40]]);Creating Polygons
This function creates a GeoJSON Polygon feature from an array of linear rings. It is used to represent areas such as city boundaries or lakes.
const polygon = turf.polygon([[[5, 10], [20, 40], [40, 0], [5, 10]]]);Leaflet is a leading open-source JavaScript library for mobile-friendly interactive maps. While Leaflet itself focuses more on map interactions and overlays, it can be used in conjunction with other tools for creating and manipulating geographic data, similar to @turf/helpers.
OpenLayers is another powerful open-source JavaScript library that handles various map-related tasks. It provides more comprehensive features for handling complex spatial operations compared to @turf/helpers, which is more focused on creating and manipulating simple geometrical features.
The Earth radius in kilometers. Used by Turf modules that model the Earth as a sphere. The mean radius was selected because it is recommended by the Haversine formula (used by turf/distance) to reduce error.
Type: number
Unit of measurement factors based on earthRadius.
Keys are the name of the unit, values are the number of that unit in a single radian
Type: Object
Area of measurement factors based on 1 square meter.
Type: Object
Wraps a GeoJSON Geometry in a GeoJSON Feature.
geometry Geometry input geometry
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};
var feature = turf.feature(geometry);
//=feature
Returns Feature a GeoJSON Feature
Creates a GeoJSON Geometry from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection
type string Geometry Typecoordinates Array<any> Coordinatesoptions Object Optional Parameters (optional, default {})var type = "Point";
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
// => geometry
Returns Geometry a GeoJSON Geometry
Creates a Point Feature from a Position.
coordinates Array<number> longitude, latitude position (each in decimal degrees)
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var point = turf.point([-75.343, 39.984]);
//=point
Returns Feature<Point> a Point feature
Creates a Point FeatureCollection from an Array of Point coordinates.
properties Object Translate these properties to each Feature (optional, default {})
options Object Optional Parameters (optional, default {})
var points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);
//=points
Returns FeatureCollection<Point> Point Feature
Creates a Polygon Feature from an Array of LinearRings.
coordinates Array<Array<Array<number>>> an array of LinearRings
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });
//=polygon
Returns Feature<Polygon> Polygon Feature
Creates a Polygon FeatureCollection from an Array of Polygon coordinates.
coordinates Array<Array<Array<Array<number>>>> an array of Polygon coordinates
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var polygons = turf.polygons([
[[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]],
[[[-15, 42], [-14, 46], [-12, 41], [-17, 44], [-15, 42]]],
]);
//=polygons
Returns FeatureCollection<Polygon> Polygon FeatureCollection
Creates a LineString Feature from an Array of Positions.
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var linestring1 = turf.lineString([[-24, 63], [-23, 60], [-25, 65], [-20, 69]], {name: 'line 1'});
var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], {name: 'line 2'});
//=linestring1
//=linestring2
Returns Feature<LineString> LineString Feature
Creates a LineString FeatureCollection from an Array of LineString coordinates.
coordinates Array<Array<Array<number>>> an array of LinearRings
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var linestrings = turf.lineStrings([
[[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
[[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
]);
//=linestrings
Returns FeatureCollection<LineString> LineString FeatureCollection
Takes one or more Features and creates a FeatureCollection.
options Object Optional Parameters (optional, default {})
var locationA = turf.point([-75.343, 39.984], {name: 'Location A'});
var locationB = turf.point([-75.833, 39.284], {name: 'Location B'});
var locationC = turf.point([-75.534, 39.123], {name: 'Location C'});
var collection = turf.featureCollection([
locationA,
locationB,
locationC
]);
//=collection
Returns FeatureCollection FeatureCollection of Features
Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.
coordinates Array<Array<Array<number>>> an array of LineStrings
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var multiLine = turf.multiLineString([[[0,0],[10,10]]]);
//=multiLine
Returns Feature<MultiLineString> a MultiLineString feature
Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var multiPt = turf.multiPoint([[0,0],[10,10]]);
//=multiPt
Returns Feature<MultiPoint> a MultiPoint feature
Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.
coordinates Array<Array<Array<Array<number>>>> an array of Polygons
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
//=multiPoly
Returns Feature<MultiPolygon> a multipolygon feature
Creates a Feature<GeometryCollection> based on a coordinate array. Properties can be added optionally.
properties Object an Object of key-value pairs to add as properties (optional, default {})
options Object Optional Parameters (optional, default {})
var pt = turf.geometry("Point", [100, 0]);
var line = turf.geometry("LineString", [[101, 0], [102, 1]]);
var collection = turf.geometryCollection([pt, line]);
// => collection
Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature
Round number to precision
turf.round(120.4321)
//=120
turf.round(120.4321, 2)
//=120.43
Returns number rounded number
Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
radians number in radians across the sphereunits string can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")Returns number distance
Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
distance number in real unitsunits string can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")Returns number radians
Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
distance number in real unitsunits string can be degrees, radians, miles, inches, yards, metres,
meters, kilometres, kilometers. (optional, default "kilometers")Returns number degrees
Converts any bearing angle from the north line direction (positive clockwise) and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line
bearing number angle, between -180 and +180 degreesReturns number angle between 0 and 360 degrees
Converts any azimuth angle from the north line direction (positive clockwise) and returns an angle between -180 and +180 degrees (positive clockwise), 0 being the north line
angle number between 0 and 360 degreesReturns number bearing between -180 and +180 degrees
Converts an angle in radians to degrees
radians number angle in radiansReturns number degrees between 0 and 360 degrees
Converts an angle in degrees to radians
degrees number angle between 0 and 360 degreesReturns number angle in radians
Converts a length to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
length number to be convertedoriginalUnit Units of the length (optional, default "kilometers")finalUnit Units returned unit (optional, default "kilometers")Returns number the converted length
Converts a area to the requested unit. Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches, hectares
area number to be convertedoriginalUnit Units of the distance (optional, default "meters")finalUnit Units returned unit (optional, default "kilometers")Returns number the converted area
isNumber
num any Number to validateturf.isNumber(123)
//=true
turf.isNumber('foo')
//=false
Returns boolean true/false
isObject
input any variable to validateturf.isObject({elevation: 10})
//=true
turf.isObject('foo')
//=false
Returns boolean true/false, including false for Arrays and Functions
This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.
Install this single module individually:
$ npm install @turf/helpers
Or install the all-encompassing @turf/turf module that includes all modules as functions:
$ npm install @turf/turf
FAQs
turf helpers module
The npm package @turf/helpers receives a total of 2,860,136 weekly downloads. As such, @turf/helpers popularity was classified as popular.
We found that @turf/helpers demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.